Workspace overview

STM32CubeIDE for Visual Studio Code combines STM32 project generation and management with standard Visual Studio Code workspace behavior. The workspace is the working context that Visual Studio Code uses for files, build tasks, debug launch configurations, source control, and extension state.

For STM32 projects, the workspace also defines the context used by the STM32CubeIDE extension. This context determines which project receives extension commands, which CMake preset applies, and which generated output is used for build and debug operations.

This distinction is important because Visual Studio Code can open any folder, but STM32CubeIDE for Visual Studio Code expects the STM32 project root to be available. Opening only a source subfolder can hide project metadata from the extension and from the CMake tools.

Workspace role

Use the workspace to manage these elements:

  • Project source files and generated startup code

  • STM32CubeMX configuration files

  • CMake presets and generated build folders

  • Visual Studio Code settings, tasks, and launch configurations

  • Build and debug output produced by the selected configuration

The workspace can contain one STM32 project or several related projects. A multi-root workspace can group projects that must be opened together, such as dual-core projects or firmware examples used by the same application.

For a single project, the project folder is usually enough. For related projects, a .code-workspace file makes the relationship explicit and lets the team reopen the same set of folders later.

Typical workflow

A typical STM32CubeIDE for Visual Studio Code workflow uses this order:

  1. Create, import, or discover an STM32 project.

  2. Open the project folder or add the project to an existing workspace.

  3. Select the CMake configure preset for the active project.

  4. Run the configure step when Visual Studio Code requests it.

  5. Build the selected target from the CMake view or an STM32CubeIDE command.

  6. Start a debug session from the Run and Debug view.

The configure step is the point where CMake converts the project description into build files for the selected preset. If the preset changes from Debug to Release, run or accept the configure step again so editor, build, and debug features use the same context.

For the first project creation flow, see First project creation.

Workspace context

The active workspace context is important when more than one project is open. Before running a command, verify that the selected project, CMake preset, and build target match the intended STM32 project.

This check is especially useful before flashing or debugging. A build command usually affects files on the computer, but a debug command can program a connected target. Confirming the context helps avoid programming the wrong board or using an outdated binary.

Use the following checks before build or debug operations:

  • The Explorer view shows the expected project folder

  • The CMake view displays the expected project and preset

  • The STM32CubeIDE extension view shows the expected project actions

  • The Run and Debug view selects the correct launch configuration

Generated and user-owned files

STM32CubeIDE for Visual Studio Code uses generated files and user-owned files in the same workspace. Treat generated files as outputs of the project configuration flow. Treat application source files, user code sections, and Visual Studio Code configuration files as files that the project team can review and version-control.

The project must keep generated files, build configuration files, and user source files in a clear structure. This structure helps the extension detect the project and helps developers understand which files they can edit safely.

Generated files can still be important source files for the build. The difference is ownership. If a tool can regenerate a file, make long-term changes in the configuration source when possible, or keep changes inside protected user sections when the generator provides them.